@opentelemetry/sdk-trace-base

What is @opentelemetry/sdk-trace-base?

The @opentelemetry/sdk-trace-base package is part of the OpenTelemetry JavaScript SDK, which provides the core functionality for tracing. It allows developers to collect and export trace data to various backends for analysis and visualization. The package includes base classes and interfaces for implementing custom trace exporters, span processors, and configuration.

What are @opentelemetry/sdk-trace-base's main functionalities?

Basic Tracer Provider Setup

This code sets up a basic tracer provider with a simple span processor that exports spans to the console. It's the starting point for setting up OpenTelemetry tracing in an application.

const { BasicTracerProvider, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { ConsoleSpanExporter } = require('@opentelemetry/tracing');

const provider = new BasicTracerProvider();
const consoleExporter = new ConsoleSpanExporter();
provider.addSpanProcessor(new SimpleSpanProcessor(consoleExporter));
provider.register();

Custom Span Processor

This code demonstrates how to create a custom span processor by extending the SpanProcessor class from the @opentelemetry/sdk-trace-base package. Developers can add custom logic for handling spans on start, on end, and during shutdown.

const { SpanProcessor } = require('@opentelemetry/sdk-trace-base');

class MySpanProcessor extends SpanProcessor {
  onStart(span) {
    // Custom logic for when a span starts.
  }

  onEnd(span) {
    // Custom logic for when a span ends.
  }

  shutdown() {
    // Custom logic for shutdown.
  }
}

Configuring a Tracer Provider

This code snippet shows how to configure a tracer provider with a specific span processor and exporter. It's a common pattern for initializing tracing in an application with OpenTelemetry.

const { BasicTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');

const provider = new BasicTracerProvider();
const exporter = new ConsoleSpanExporter();
const processor = new SimpleSpanProcessor(exporter);

provider.addSpanProcessor(processor);
provider.register();

Other packages similar to @opentelemetry/sdk-trace-base

jaeger-client

The jaeger-client package is a Node.js client for Jaeger, a distributed tracing system. It provides similar functionality to @opentelemetry/sdk-trace-base, allowing developers to send trace data to a Jaeger backend. However, it is specific to Jaeger, whereas OpenTelemetry provides a more vendor-neutral approach.

zipkin-javascript-opentracing

This package is an OpenTracing-compatible tracer implementation for Zipkin in JavaScript. Like @opentelemetry/sdk-trace-base, it enables tracing and exporting trace data but is tailored for integration with Zipkin, a different distributed tracing system.

lightstep-tracer

Lightstep's tracer library for JavaScript is designed to monitor and trace application performance. It is similar to @opentelemetry/sdk-trace-base in that it collects trace data, but it is specifically built to work with Lightstep's performance monitoring platform.

README

OpenTelemetry Tracing SDK

The tracing module contains the foundation for all tracing SDKs of opentelemetry-js.

Used standalone, this module provides methods for manual instrumentation of code, offering full control over span creation for client-side JavaScript (browser) and Node.js.

It does not provide automated instrumentation of known libraries, context propagation for asynchronous invocations or distributed-context out-of-the-box.

For automated instrumentation for Node.js, please see @opentelemetry/sdk-trace-node.

Installation

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-base

Usage

const opentelemetry = require('@opentelemetry/api');
const { BasicTracerProvider } = require('@opentelemetry/sdk-trace-base');

// To start a trace, you first need to initialize the Tracer provider.
// NOTE: The default OpenTelemetry tracer provider does not record any tracing information.
//       Registering a working tracer provider allows the API methods to record traces.
new BasicTracerProvider().register();

// To create a span in a trace, we used the global singleton tracer to start a new span.
const span = opentelemetry.trace.getTracer('default').startSpan('foo');

// Set a span attribute
span.setAttribute('key', 'value');

// We must end the spans so they become available for exporting.
span.end();

Config

Tracing configuration is a merge of user supplied configuration with both the default configuration as specified in config.ts and an environmentally configurable sampling (via OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG).

Built-in Samplers

Sampler is used to make decisions on Span sampling.

AlwaysOn Sampler

Samples every trace regardless of upstream sampling decisions.

This is used as a default Sampler

const {
  AlwaysOnSampler,
  BasicTracerProvider,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  sampler: new AlwaysOnSampler()
});

AlwaysOff Sampler

Doesn't sample any trace, regardless of upstream sampling decisions.

const {
  AlwaysOffSampler,
  BasicTracerProvider,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  sampler: new AlwaysOffSampler()
});

TraceIdRatioBased Sampler

Samples some percentage of traces, calculated deterministically using the trace ID. Any trace that would be sampled at a given percentage will also be sampled at any higher percentage.

The TraceIDRatioSampler may be used with the ParentBasedSampler to respect the sampled flag of an incoming trace.

const {
  BasicTracerProvider,
  TraceIdRatioBasedSampler,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  // See details of ParentBasedSampler below
  sampler: new ParentBasedSampler({
    // Trace ID Ratio Sampler accepts a positional argument
    // which represents the percentage of traces which should
    // be sampled.
    root: new TraceIdRatioBasedSampler(0.5)
  });
});

ParentBased Sampler

• This is a composite sampler. ParentBased helps distinguished between the following cases:
  • No parent (root span).
  • Remote parent with sampled flag true
  • Remote parent with sampled flag false
  • Local parent with sampled flag true
  • Local parent with sampled flag false

Required parameters:

• root(Sampler) - Sampler called for spans with no parent (root spans)

Optional parameters:

• remoteParentSampled(Sampler) (default: AlwaysOn)
• remoteParentNotSampled(Sampler) (default: AlwaysOff)
• localParentSampled(Sampler) (default: AlwaysOn)
• localParentNotSampled(Sampler) (default: AlwaysOff)

Parent	parent.isRemote()	parent.isSampled()	Invoke sampler
absent	n/a	n/a	root()
present	true	true	remoteParentSampled()
present	true	false	remoteParentNotSampled()
present	false	true	localParentSampled()
present	false	false	localParentNotSampled()

const {
  AlwaysOffSampler,
  BasicTracerProvider,
  ParentBasedSampler,
  TraceIdRatioBasedSampler,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  sampler: new ParentBasedSampler({
    // By default, the ParentBasedSampler will respect the parent span's sampling
    // decision. This is configurable by providing a different sampler to use
    // based on the situation. See configuration details above.
    //
    // This will delegate the sampling decision of all root traces (no parent)
    // to the TraceIdRatioBasedSampler.
    // See details of TraceIdRatioBasedSampler above.
    root: new TraceIdRatioBasedSampler(0.5)
  })
});

Example

See examples/basic-tracer-node for an end-to-end example, including exporting created spans.

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.

Changelog

1.27.0

:rocket: (Enhancement)

• feat: add processors for adding session.id attribute to spans and logs #4972

:bug: (Bug Fix)

• fix(sdk-trace-base): avoid keeping non-string status.message on Span#setStatus() #4999 @pichlermarc
• fix(sdk-metrics): Add missing catch and handle error in promise of PeriodicExportingMetricReader #5006 @jj22ee
• fix(opentelemetry-core): confusing log extract of composite propagator #5017 @rv2673
• fix(propagator-aws-xray-*): move propagators back to contrib repository #4966 @pichlermarc
  • The specification prohibits hosting these packages in the core repository
  • @opentelemetry/propagator-aws-xray is now located in open-telemetry/opentelemetry-js-contrib
  • @opentelemetry/propagator-aws-xray-lambda is now located in open-telemetry/opentelemetry-js-contrib

:house: (Internal)

• deps: set @opentelemetry/api dependency min version to 1.3.0 in examples, experimental/packages, integration-tests and selenium-tests #4992
• refactor(sdk-metrics): replace MetricsAttributes with Attributes #5021 @david-luna
• refactor(instrumentation-http): replace SpanAttributes and MetricsAttributes with Attributes #5023 @david-luna
• chore(exporter-zipkin): remove usages of Span constructor #5030 @david-luna
• test(instrumentation-http): remove usages of new Span in tests #5035 @david-luna